//+------------------------------------------------------------------+
//|                ChartObjectsLines.mqh MQL5 图表线型工具头文件      |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
//| 包含所有基础图表线型对象类（垂直线、水平线、趋势线、角度趋势线、周期线） |
//+------------------------------------------------------------------+
#include "ChartObject.h"  // 引入图表对象基类 CChartObject（提供通用属性与生命周期管理）

//+------------------------------------------------------------------+
//| CChartObjectVLine 类（垂直线条对象）                              |
//| 功能：MQL5 图表垂直线条工具，用于标记特定时间节点（如重要事件、交易信号时间） |
//| 继承关系：public CChartObject（基于基础图表对象类，无额外依赖）    |
//| 核心特性：                                                      |
//|  1. 时间轴定位：仅依赖时间坐标（Time），垂直贯穿整个图表窗口        |
//|  2. 全局显示：线条高度自适应图表窗口，不受价格轴缩放影响            |
//|  3. 时间标记：适用于标记非农数据发布、政策公告等时间敏感节点        |
//+------------------------------------------------------------------+
class CChartObjectVLine : public CChartObject
  {
public:
   /**
    * @brief 构造函数：初始化垂直线条对象
    * @details 调用父类 CChartObject 构造函数，初始化基础属性（未绑定图表）
    */
                     CChartObjectVLine(void);

   /**
    * @brief 析构函数：销毁垂直线条对象
    * @details 依赖父类析构逻辑，自动删除图表上的垂直线，释放资源
    */
                    ~CChartObjectVLine(void);

   /**
    * @brief 在指定图表创建垂直线条（通过时间坐标定义）
    * @param chart_id [in] 目标图表 ID（0 表示当前图表，可通过 ChartID() 获取）
    * @param name [in] 垂直线唯一名称（图表内不可重复）
    * @param window [in] 子窗口编号（0=主窗口，≥1=指标子窗口）
    * @param time [in] 垂直线对应的时间坐标（如 D'2024.01.01'，线条将垂直穿过该时间点）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定完成），false 表示失败
    * @note 价格参数无意义（内部设为 0.0），线条垂直贯穿整个窗口，随时间轴缩放移动
    */
   bool              Create(long chart_id,const string name,const int window,const datetime time);

   /**
    * @brief 获取垂直线条对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_VLINE，代表垂直线条）
    */
   virtual int       Type(void) const { return(OBJ_VLINE); }
  };

//+------------------------------------------------------------------+
//| CChartObjectHLine 类（水平线条对象）                              |
//| 功能：MQL5 图表水平线条工具，用于标记关键价格水平（如支撑位、阻力位、均线值） |
//| 继承关系：public CChartObject（基于基础图表对象类，无额外依赖）    |
//| 核心特性：                                                      |
//|  1. 价格轴定位：仅依赖价格坐标（Price），水平贯穿整个图表窗口        |
//|  2. 全局显示：线条宽度自适应图表窗口，不受时间轴缩放影响            |
//|  3. 价格标记：适用于标记历史高点/低点、止损价、止盈价等关键价位        |
//+------------------------------------------------------------------+
class CChartObjectHLine : public CChartObject
  {
public:
   /**
    * @brief 构造函数：初始化水平线条对象
    * @details 调用父类 CChartObject 构造函数，初始化基础属性（未绑定图表）
    */
                     CChartObjectHLine(void);

   /**
    * @brief 析构函数：销毁水平线条对象
    * @details 依赖父类析构逻辑，自动删除图表上的水平线，释放资源
    */
                    ~CChartObjectHLine(void);

   /**
    * @brief 在指定图表创建水平线条（通过价格坐标定义）
    * @param chart_id [in] 目标图表 ID
    * @param name [in] 水平线唯一名称
    * @param window [in] 子窗口编号
    * @param price [in] 水平线对应的价格坐标（如 1.20000，线条将水平穿过该价格点）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定完成），false 表示失败
    * @note 时间参数无意义（内部设为 0），线条水平贯穿整个窗口，随价格轴缩放移动
    */
   bool              Create(long chart_id,const string name,const int window,const double price);

   /**
    * @brief 获取水平线条对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_HLINE，代表水平线条）
    */
   virtual int       Type(void) const { return(OBJ_HLINE); }
  };

//+------------------------------------------------------------------+
//| CChartObjectTrend 类（趋势线条对象）                              |
//| 功能：MQL5 图表趋势线条工具，用于标记价格趋势方向（上升/下降/横盘）   |
//| 继承关系：public CChartObject（基于基础图表对象类，为角度趋势线等子类提供基类） |
//| 核心特性：                                                      |
//|  1. 两点定义趋势：通过“起点（时间1,价格1）”和“终点（时间2,价格2）”确定趋势方向与斜率 |
//|  2. 射线延伸控制：支持左右射线延伸（RayLeft/RayRight），预测趋势延续方向 |
//|  3. 趋势识别：适用于连接高点/低点形成趋势线，判断价格突破后的趋势反转信号 |
//+------------------------------------------------------------------+
class CChartObjectTrend : public CChartObject
  {
public:
   /**
    * @brief 构造函数：初始化趋势线条对象
    * @details 调用父类 CChartObject 构造函数，初始化基础属性（未绑定图表）
    */
                     CChartObjectTrend(void);

   /**
    * @brief 析构函数：销毁趋势线条对象
    * @details 依赖父类析构逻辑，自动删除图表上的趋势线，释放资源
    */
                    ~CChartObjectTrend(void);

   //--- 趋势线特有属性接口（射线延伸控制）
   /**
    * @brief 获取左侧射线延伸状态（线条向起点左侧延伸）
    * @return bool - 状态值：true=开启左侧延伸（线条向左无限延伸，预测历史趋势延续），false=关闭
    */
   bool              RayLeft(void) const;

   /**
    * @brief 设置左侧射线延伸状态
    * @param new_ray [in] 新状态（true=开启，false=关闭）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    */
   bool              RayLeft(const bool new_ray) const;

   /**
    * @brief 获取右侧射线延伸状态（线条向终点右侧延伸）
    * @return bool - 状态值：true=开启右侧延伸（线条向右无限延伸，预测未来趋势延续），false=关闭
    */
   bool              RayRight(void) const;

   /**
    * @brief 设置右侧射线延伸状态
    * @param new_ray [in] 新状态（true=开启，false=关闭）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    * @note 右侧延伸常用于趋势预测，左侧延伸常用于补充历史趋势完整性
    */
   bool              RayRight(const bool new_ray) const;

   /**
    * @brief 在指定图表创建趋势线条（通过两点坐标定义）
    * @param chart_id [in] 目标图表 ID
    * @param name [in] 趋势线唯一名称
    * @param window [in] 子窗口编号
    * @param time1 [in] 起点时间坐标（如趋势启动 K 线时间）
    * @param price1 [in] 起点价格坐标（如趋势启动价格）
    * @param time2 [in] 终点时间坐标（如趋势阶段性高点/低点 K 线时间）
    * @param price2 [in] 终点价格坐标（如趋势阶段性高点/低点价格）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定完成），false 表示失败
    * @note 两点需按时间顺序排列（time1 < time2），价格关系决定趋势方向（price2 > price1 为上升趋势）
    */
   bool              Create(long chart_id,const string name,const int window,
                            const datetime time1,const double price1,
                            const datetime time2,const double price2);

   /**
    * @brief 获取趋势线条对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_TREND，代表趋势线条）
    */
   virtual int       Type(void) const { return(OBJ_TREND); }

   /**
    * @brief 将趋势线参数（含射线延伸属性）保存到文件
    * @param file_handle [in] 文件句柄（需提前以 FILE_WRITE 模式打开）
    * @return bool - 操作结果：true 表示保存成功，false 表示失败（文件无效/未绑定图表）
    * @note 保存内容：基类通用属性 + 左侧射线状态（RayLeft） + 右侧射线状态（RayRight）
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从文件加载趋势线参数（含射线延伸属性）
    * @param file_handle [in] 文件句柄（需提前以 FILE_READ 模式打开）
    * @return bool - 操作结果：true 表示加载成功，false 表示失败（文件无效/未绑定图表）
    */
   virtual bool      Load(const int file_handle);
  };

//+------------------------------------------------------------------+
//| CChartObjectTrendByAngle 类（角度趋势线条对象）                    |
//| 功能：MQL5 图表角度趋势线工具，通过固定角度绘制趋势线，精确控制趋势斜率 |
//| 继承关系：public CChartObjectTrend（基于趋势线基类，扩展角度控制属性） |
//| 核心特性：                                                      |
//|  1. 角度驱动：支持直接设置线条角度（如 45° 代表强上升趋势），不受两点距离影响 |
//|  2. 继承射线延伸：复用父类的 RayLeft/RayRight 属性，支持趋势预测    |
//|  3. 精确趋势分析：适用于需要固定斜率的场景（如江恩理论中的角度线分析） |
//+------------------------------------------------------------------+
class CChartObjectTrendByAngle : public CChartObjectTrend
  {
public:
   /**
    * @brief 构造函数：初始化角度趋势线条对象
    * @details 调用父类 CChartObjectTrend 构造函数，继承趋势线基础属性与射线延伸功能
    */
                     CChartObjectTrendByAngle(void);

   /**
    * @brief 析构函数：销毁角度趋势线条对象
    * @details 依赖父类析构逻辑，自动删除图表上的角度趋势线，释放资源
    */
                    ~CChartObjectTrendByAngle(void);

   //--- 角度趋势线特有属性接口（角度控制）
   /**
    * @brief 获取趋势线的当前角度（相对于水平轴）
    * @return double - 角度值（单位：度，范围 -90°~90°，0° 为水平线，45° 为强上升，-45° 为强下降）
    */
   double            Angle(void) const;

   /**
    * @brief 设置趋势线的角度（固定斜率）
    * @param angle [in] 新角度值（单位：度，建议范围 -60°~60°，避免极端角度导致线条失真）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定图表）
    * @note 角度设置后，线条斜率固定，拖动锚点仅改变位置，不改变角度
    */
   bool              Angle(const double angle) const;

   /**
    * @brief 在指定图表创建角度趋势线条（通过两点坐标初始化，后续可调整角度）
    * @param chart_id [in] 目标图表 ID
    * @param name [in] 角度趋势线唯一名称
    * @param window [in] 子窗口编号
    * @param time1 [in] 起点时间坐标（线条位置基准点）
    * @param price1 [in] 起点价格坐标（线条位置基准点）
    * @param time2 [in] 终点时间坐标（仅用于初始化线条长度，不影响最终角度）
    * @param price2 [in] 终点价格坐标（仅用于初始化线条长度，不影响最终角度）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定完成），false 表示失败
    * @note 创建后建议通过 Angle 方法设置目标角度，初始化两点仅用于确定线条的初始位置与长度
    */
   bool              Create(long chart_id,const string name,const int window,
                            const datetime time1,const double price1,
                            const datetime time2,const double price2);

   /**
    * @brief 获取角度趋势线条对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_TRENDBYANGLE，代表角度趋势线条）
    */
   virtual int       Type(void) const { return(OBJ_TRENDBYANGLE); }
  };

//+------------------------------------------------------------------+
//| CChartObjectCycles 类（周期线条对象）                            |
//| 功能：MQL5 图表周期线条工具，用于标记价格波动的周期性节点（如波段周期、时间周期） |
//| 继承关系：public CChartObject（基于基础图表对象类，无额外依赖）    |
//| 核心特性：                                                      |
//|  1. 周期基准定义：通过两点坐标确定周期长度（时间差或价格差），自动生成等距周期线 |
//|  2. 双向延伸：周期线向两点两侧自动延伸，覆盖整个图表窗口            |
//|  3. 周期分析：适用于识别价格的周期性波动（如斐波那契时间周期、季节性周期） |
//+------------------------------------------------------------------+
class CChartObjectCycles : public CChartObject
  {
public:
   /**
    * @brief 构造函数：初始化周期线条对象
    * @details 调用父类 CChartObject 构造函数，初始化基础属性（未绑定图表）
    */
                     CChartObjectCycles(void);

   /**
    * @brief 析构函数：销毁周期线条对象
    * @details 依赖父类析构逻辑，自动删除图表上的周期线，释放资源
    */
                    ~CChartObjectCycles(void);

   /**
    * @brief 在指定图表创建周期线条（通过两点坐标定义周期基准）
    * @param chart_id [in] 目标图表 ID
    * @param name [in] 周期线唯一名称
    * @param window [in] 子窗口编号
    * @param time1 [in] 周期起点时间坐标（如第一个周期节点时间）
    * @param price1 [in] 周期起点价格坐标（如第一个周期节点价格，通常与 time1 对应同一K线）
    * @param time2 [in] 周期终点时间坐标（如第二个周期节点时间，与 time1 形成一个完整周期）
    * @param price2 [in] 周期终点价格坐标（如第二个周期节点价格，通常与 time2 对应同一K线）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定+周期计算完成），false 表示失败
    * @note 周期长度由两点的时间差决定（time2 - time1），价格参数仅用于定位周期线的垂直位置
    */
   bool              Create(long chart_id,const string name,const int window,
                            const datetime time1,const double price1,
                            const datetime time2,const double price2);

   /**
    * @brief 获取周期线条对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_CYCLES，代表周期线条）
    */
   virtual int       Type(void) const { return(OBJ_CYCLES); }
  };
//+------------------------------------------------------------------+